@js-temporal/polyfill

What is @js-temporal/polyfill?

@js-temporal/polyfill is a polyfill for the Temporal API, which is a modern date/time API for JavaScript. It provides a more comprehensive and accurate way to handle dates and times compared to the built-in Date object.

What are @js-temporal/polyfill's main functionalities?

Creating Temporal Objects

This feature allows you to create various Temporal objects such as PlainDateTime, PlainDate, PlainTime, etc. The code sample demonstrates creating a PlainDateTime object representing the current date and time in ISO format.

const { Temporal } = require('@js-temporal/polyfill');
const now = Temporal.Now.plainDateTimeISO();
console.log(now.toString());

Date Arithmetic

Temporal makes it easy to perform date arithmetic. The code sample shows how to add one day to the current date to get tomorrow's date.

const { Temporal } = require('@js-temporal/polyfill');
const today = Temporal.Now.plainDateISO();
const tomorrow = today.add({ days: 1 });
console.log(tomorrow.toString());

Time Zones

Temporal provides robust support for time zones. The code sample demonstrates how to get the current date and time in a specific time zone (America/New_York).

const { Temporal } = require('@js-temporal/polyfill');
const now = Temporal.Now.zonedDateTimeISO();
const timeZone = Temporal.TimeZone.from('America/New_York');
const nyTime = now.withTimeZone(timeZone);
console.log(nyTime.toString());

Duration and Intervals

Temporal allows you to work with durations and intervals. The code sample shows how to calculate the duration between two dates.

const { Temporal } = require('@js-temporal/polyfill');
const start = Temporal.PlainDate.from('2023-01-01');
const end = Temporal.PlainDate.from('2023-12-31');
const duration = end.since(start);
console.log(duration.toString());

Other packages similar to @js-temporal/polyfill

moment

Moment.js is a widely-used library for parsing, validating, manipulating, and formatting dates. While it is very powerful, it is also quite large and has been deprecated in favor of more modern solutions like Temporal.

date-fns

date-fns provides a comprehensive set of functions for working with dates in JavaScript. It is modular, allowing you to import only the functions you need, which can result in smaller bundle sizes compared to Moment.js.

luxon

Luxon is a modern library for working with dates and times in JavaScript. It is built on top of the native Intl API and provides a more modern API compared to Moment.js. Luxon is similar to Temporal in its approach to handling dates and times.

README

Temporal Polyfill

Polyfill for TC39 Proposal: Temporal

This polyfill was kicked off by some of the champions of the Temporal proposal. The goal is to be ready for production use when the Temporal proposal reaches Stage 4, although like with all OSS work progress is dependent on contributors. We're eagerly welcoming to contributors who want to help build and maintain this polyfill. PRs are always welcome!

Note that this polyfill is not affiliated with TC39. Links to other polyfills can be found here.

This polyfill is compatible with Node.js 14 or later.

Roadmap

• Fork non-production polyfill from tc39/proposal-temporal repo
• Release initial pre-alpha to NPM at @js-temporal/polyfill
• Sync the code in this repo with the handful of polyfill changes that have recently been made in the tc39/proposal-temporal repo
• Release alpha version to NPM
• Deprecate all other earlier Temporal polyfills
• Optimize slow operations by reducing calls to Intl.DateTimeFormat constructor (see #7, #8, #10, #12)
• Convert to TypeScript for better maintainability
• Improve typing of sources for better maintainability
• Migrate to JSBI for improved compile-time safety around BigInt operations.
• Optimize performance of other slow operations
• Release production version to NPM

Bug Reports and Feedback

If you think you've found a bug in the Temporal API itself (not the implementation in this polyfill), please file an issue in the tc39/proposal-temporal issue tracker issue tracker.

If you've found a bug in this polyfill—meaning that the implementation here doesn't match the Temporal spec—please file an issue in this repo's issue tracker.

Documentation

Reference documentation and examples for the Temporal API can be found here.

A cookbook to help you get started and learn the ins and outs of Temporal is available here

If you find a bug in the documentation, please file a bug over in the tc39/proposal-temporal issue tracker issue tracker.

Note that the Temporal documentation is in the process of being migrated to MDN. You can track the progress of the MDN migration here.

Usage

To install:

$ npm install @js-temporal/polyfill

CJS Usage:

const { Temporal, Intl, toTemporalInstant } = require('@js-temporal/polyfill');
Date.prototype.toTemporalInstant = toTemporalInstant;

Import the polyfill as an ES6 module:

import { Temporal, Intl, toTemporalInstant } from '@js-temporal/polyfill';
Date.prototype.toTemporalInstant = toTemporalInstant;

Note that this polyfill currently does not install a global Temporal object like a real implementation will. This behavior avoids hiding the global Temporal object in environments where a real Temporal implementation is present. See this issue for more background on this decision. Once JS engines start shipping with Temporal, we may decide to change this behavior to match built-in behavior more closely. See #2 to provide feedback or track this issue.

This polyfill ships ES2020 code for both CJS and ESM bundles - if your environment does not support ES2020, then please make sure to transpile the content of this package along with the rest of your code.

This polyfill uses JSBI to enable backwards-compatibility for environments that don't support native bigints. If your project only ever runs in environments that do support native bigints (see caniuse data), we highly recommend configuring the JSBI Babel plugin that translates JSBI calls to their native bigint equivalent, improving code-size and performance. We are exploring ways to provide separate builds for these use-cases in #155.

Contributing / Help Wanted

We're eagerly welcoming to contributors who want to help build and maintain this polyfill. PRs are always welcome!